home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -screenplay- / hd_installers / -whdload- / whdload_dev / patcher1.05dev.lha / Patcher1.05 / PatcherDeveloper.readme < prev    next >
Text File  |  1998-01-17  |  12KB  |  284 lines
  1. Programmers description:
  2. MAKECOMPTAB gives the differences in a way which is used in a module. 
  3. Options are:
  4. MAKECOMPTAB ?    - gives a short description
  5. MAKECOMPTAB "original" "patchedfile" {"tableoutput"}
  6.     - compares original with patched file and writes the differences 
  7.       to tableoutput, if specified.
  8. Commandline for Directoryopus is: Makecomptab "{fu}" "{d}{ou}" "RAM:table_{o}"
  9. It compares the selected file in the source window with the equal named 
  10. file in the destination window and writes the table of differences to RAM:.
  11.  
  12. If you dont understand the following text, please look at the examples 
  13. for modules. I find it easier to see an example and a description 
  14. together cause it is complicate to explain some things here under-
  15. standable.
  16.  
  17. Structure of a module for The Patcher:
  18.     MOVEQ.L    #20,D0        ;four fillbytes (reserved!)
  19.     RTS
  20.     DC.L    TABLE        ;pointer on the tagarray
  21.     DC.B    'PTCH'        ;for recognizing module
  22.     ...
  23. TABLE    {TAGS}
  24.     DC.L    TAG_DONE
  25.     ...
  26.  
  27.  
  28. Supported tags:
  29.  
  30. TAG_DONE        = $00000000
  31. Finishes the tagtable.
  32.  
  33. PCH_ADAPTOR        = $80004451
  34.     DC.L    {^yourname}
  35. Name of the people which did the fixing work :). Maximally 2 lines of 
  36. appr. 40 characters, each line finished by $A and the text ended with $0. 
  37. This tag is necessary.
  38.  
  39. PCH_NAME        = $80004458
  40.     DC.L    {^parametername}
  41. Name of the game, max. 1 line of appr. 40 characters. The filename of the 
  42. parameter itself is meaningless. This tag is necessary.
  43.  
  44. PCH_FILECOUNT        = $80004450
  45.     DC.L    {#filecount}    
  46. Number of cycles to execute, mostly equal to the total number of the files 
  47. to modify or save (all disks added). This tag is necessary.
  48.  
  49. PCH_FILENAME        = $80004454
  50.     DC.L    {^array of ^filenames}
  51. Points on an array of the pointers on the filenames (with path). 
  52.  
  53. PCH_DISKNAME        = $80004452
  54.     DC.L    {^array of ^disknames}
  55. Points on an array of the pointers on the disknames (without : !!).
  56.  
  57. PCH_CHANGES        = $80004456
  58.     DC.L    {^array of ^changestables}
  59. Points on an array of the pointers on the changestables obtained by 
  60. MAKECOMPTAB.
  61.  
  62. PCH_CHECKDISK        = $80004453
  63.     DC.L    {^array of ^ckeckroutines}
  64. Points on an array of the pointers on the customcheckroutines. This tag is 
  65. only necessary if you want to recognize a nonstandard disk (but i prefer to 
  66. recognize the disk in the PCH_SPECIAL-routine).
  67.  
  68. PCH_MINVERSION        = $80004459
  69.     DC.L    {^versionstring}
  70. If your parameter requires a feature of a higher version of THE PATCHER, 
  71. you can set a versionstring. Useful eg for commandline-parameters.
  72. Stringformat: DC.B    'V1.03',0
  73.  
  74. PCH_PROCESSING        = $80004457
  75.     DC.L    {^array of ^processingroutines}
  76. Points on an array of the pointers on specialroutines. Such a specialroutine
  77. can be a decryptroutine. For more information look at the parameter 
  78. of populous.
  79.  
  80. PCH_LOADOFFSET        = $8000445A
  81.     DC.L    {^array of offsets}
  82. Points on an array of offsets of the loaded file, this means the file 
  83. will be appended on that space. Required for changing the startup-sequence
  84. if you want to insert a line at the top (for ex. FIRST{Return}, then you 
  85. have an offset of 6).
  86.  
  87. PCH_APPENDSPACE        = $8000445E
  88.     DC.L    {^array of space}
  89. Points on an array of space appended on the loaded file, this means the space 
  90. will be appended on that file. Required for changing the startup-sequence
  91. if you want to insert a line at the bottom (for ex. LAST{Return}, then you 
  92. have an space of 5).
  93.  
  94. PCH_STATE        = $8000445C
  95.     DC.L    {^array of ^statetexts}
  96. Points on an array of pointers on statetexts. Required for nonstandard 
  97. disks, when you need a formatconversion and will have to read the original 
  98. disk so that you have to write "Please insert your original writeprotected 
  99. disk." instead of "Please insert a copy of your disk and wait for 
  100. processing.".
  101.  
  102. PCH_STATE2        = $8000445D
  103.     DC.L    {^array of ^statetexts2}
  104. Points on an array of pointers on statetexts. Required for nonstandard 
  105. disks, when you need a formatconversion and will have to write to the  
  106. destination disk so that you must write "Please insert your destination 
  107. disk." instead of "Please insert a copy of your disk and wait for 
  108. processing.".
  109.  
  110. PCH_INIT        = $8000445B
  111.     DC.L    {^initialisation routine}
  112. If a parameter must be initialized, you can do that here.
  113.  
  114. PCH_SPECIAL        = $80004455
  115.     DC.L    {^array of ^specialroutines}
  116. Here could be routines for loading data of a nonstandard disk.
  117.  
  118. PCH_SAVEPGM        = $80004464
  119.     DC.L    {^array of ^specialroutines}
  120. Here could be routines for saving data on a nonstandard disk.
  121.  
  122. PCH_SAVEDATA        = $8000445F
  123.     DC.L    {^array of ^datatables}
  124. Needed if you have to save an additional file to disk.
  125.  
  126. PCH_DATALENGTH        = $80004460
  127.     DC.L    {^array of lengths of data to save}
  128. Needed when a formatconversion is made or you have to save an additional 
  129. file on the disk. Or you use it to ensure the correct version of the 
  130. game.
  131.  
  132. PCH_BOOTBLOCK        = $80004461
  133.     DC.L    {^array of ^bootblocks}
  134. Saves the declared bootblock on disk. The Bootblock has to be in chipmemory!
  135.  
  136. PCH_FINISH        = $80004462
  137.     DC.L    {^finishing routine}
  138. If a parameter has to do some finishing-code (eg freeing self-allocated 
  139. memory), you can do that here.
  140.  
  141. PCH_ERRORINPARAMETER    = $80004463
  142.     DC.L    {^error routine}
  143. If an error occured and a parameter has to do some finishing-code, you can do 
  144. that here.
  145.  
  146.  
  147. Running:
  148. It clears the area given by PTB_SPACE.
  149. At first it checks if an initroutine (PCH_INIT) is present.
  150. Then it detects the number of cycles (PCH_FILECOUNT).
  151. Now it moves #0,D6.
  152. Now begins the cyclic program:
  153.  It tries to write out the state (PCH_STATE).
  154.  Then it tries to get the diskname (PCH_DISKNAME) and to check for the 
  155.  diskvolume.
  156.  Then it would execute a customcheckroutine for the disk (PCH_CHECKDISK).
  157.  Then it gets the filename (PCH_FILENAME).
  158.   If there is a tag for a customroutine (PCH_SPECIAL), it would 
  159.   happen the following:
  160.    It accounts the RAM given by PCH_DATALENGTH (obviously in that case it is 
  161.    needed). PTB_ADDRESSOFFILE points on that area.
  162.    It doesnt load the file given by the filename, but executes your 
  163.    customroutine, which could be a loading routine.
  164.    Now it writes out the save state (PCH_STATE2) if present.
  165.    Then it executes a routine if PCH_PROCESSING is present. 
  166.    Then it makes the changes given by PCH_CHANGES.
  167.    Then it will execute the routine given by PCH_SAVEPGM.
  168.    Then it will save the file (only if a filename was given). Cycle ends.
  169.   If there is a tag for saving a bootblock (PCH_BOOTBLOCK), 
  170.    it tries to write out the message of PCH_STATE2.
  171.    Then the bootblock will be saved. Cycle ends.
  172.   If there is a tag for saving a file (PCH_SAVEDATA),
  173.    the length of that file will be given by PCH_DATALENGTH.
  174.    It tries to write out the message given by PCH_STATE2.
  175.    Then the file will be saved.
  176.   Otherwise it will execute the following:
  177.    It gets the length of the file.
  178.    Then it tries to detect PCH_LOADOFFSET and PCH_APPENDSPACE and 
  179.    evaluates the filelength.
  180.    Then it compares the filelength with the length given by PCH_DATALENGTH
  181.    (if present) and cancels the parameter processing if not equal.
  182.    Then it would account the RAM evaluated and load that file.
  183.    Now it writes out the save state (PCH_STATE2) if present.
  184.    Then it executes a routine if PCH_PROCESSING is present. See also 
  185.    the example of Populous.
  186.    Then it makes the changes given by PCH_CHANGES.
  187.    Then it will save the file.
  188. Here ends the cyclic program.
  189. If there is a finishing routine {PCH_FINISH} it will be executed.
  190. Source- and destinationdevice will be closed, if it were opened.
  191. It is impossible to check all correct combinations, so FIRST think about it 
  192. and then plan a module. When you give the tag PCH_SAVEDATA and no filename, 
  193. an error will occur or the program crashes!
  194.  
  195. In the routines in the cyclic programexecution D6 gives the actual cycle. Look
  196. at the example of imagergemx.
  197. On all moduleroutines A5 points on the following area:
  198. PTB_DOSBASE        = $0    Base of the dos.library.
  199. PTB_ADDRESSOFFILE    = $4    Points on the filedata.
  200. PTB_INTUITIONBASE    = $8    Base of the intuition.library.
  201. PTB_GFXBASE        = $C    Base of the graphics.library.
  202. PTB_WINDOW        = $10    Points on the structure Window.
  203. PTB_FILENAME        = $14    Points on the filename.
  204. PTB_FULLNAME        = $18    Points on the filename with the volumename.
  205. PTB_FILESIZE        = $1C    Gives the filesize.
  206. PTB_DISKNAME        = $20    Points on the volumename.
  207. PTB_OPENDEVICE        = $24    Points on a routine to open the device 
  208.                 specified in the CLI. Needed only if you 
  209.                 have to convert a nonstandard disk.
  210.                 D0 = 0    opens for source
  211.                 D0 = 1    opens for destination
  212. PTB_DEVICESOURCEPTR    = $28    If you called PTB_OPENDEVICE with D0=0, this 
  213.                 shows the base of the source device, otherwise 
  214.                 it is 0.
  215. PTB_DEVICEDESTPTR    = $2C    If you called PTB_OPENDEVICE with D0=1, this 
  216.                 shows the base of the destination device, 
  217.                 otherwise it is 0.
  218. PTB_SPACE        = $30    Points on a chipmem-area of $C000 bytes for 
  219.                 buffering any data (not used in the main 
  220.                 program).
  221. PTB_FORMATDEST        = $34    Formats a dd-disk in the destination drive,
  222.                 when called with D0=0. Returns D0=0 on success.
  223. PTB_REQUEST        = $38    Shows a Ok-Cancel-requester. Two lines of
  224.                 text are allowed, given in A0 and A1.
  225.                 Returns D0=0 on Ok and -1 on Cancel.
  226. New in version 1.02:
  227. PTB_FSSMSOURCEPTR    = $3C    If PTB_OPENDEVICE was successfully called the
  228. PTB_FSSMDESTPTR        = $40    corresponding PTB_FSSM*PTR points on the
  229.                 FileSystemStartupMessage-structure of that
  230.                 device.
  231. PTB_INHIBITDRIVE    = $44    Inhibits the source-drive, when called with
  232.                 D0=0 and the destination-drive when called 
  233.                 with D0=1. Returns D0=0 on success.
  234. PTB_ENABLEDRIVE        = $48    Enables the inhibited source-drive when 
  235.                 called with D0=0 and the destinationdrive when
  236.                 called with D0=1. Returns D0=0 on success.
  237.  
  238. New in version 1.03:
  239. PTB_CRC16        = $4C    Returns in D0 a 16-bit-CRC of an area given by
  240.                 a pointer in A0    and a length in D0.
  241.  
  242. New in version 1.05:
  243. PTB_DISPLAY        = $50    Displays the string in A0 in the messagearea.
  244.                 Maximally 2 lines of appr. 40 characters, 
  245.                 each line finished by $A and the text ended 
  246.                 with $0. Look at the example of the encounter-
  247.                 imager.
  248.  
  249. You can use all registers in your module, the regs are rescued on 
  250. the stack before executing your program.
  251.  
  252. All routines must return 0 in D0 if all went ok.
  253.  
  254. The parameters may contain all kind of hunks and memorytypes.
  255.  
  256. Please dont change the tags itself of a parameter while execution. The 
  257. value of the tags and the tables itself may be changed in execution 
  258. (see at the example of imagernitro), but AT LEAST ONE cycle before they 
  259. are needed, eg you may change stuff for cycle 1 in PCH_INIT, stuff for 
  260. cycle 3 in cycle 2 and so on. The only exception from that rule is 
  261. PCH_CHANGES which may be changed at any time before use.
  262. If you have to convert a nst-disk to files and you get your filenames from
  263. the disk, you can use 2 spaces for filenames alternating and set the one 
  264. which is unused in the current cycle.
  265.  
  266. Sorry, but all examples can be assembled only with uppercase=lowercase.
  267.  
  268. Tricks:
  269. If you want to insert a line at the top of the startup-sequence, please 
  270. change the startup-sequence once to the destination and once insert only
  271. fillbytes (for ex. @) instead. Then use the true startup-sequence as 
  272. patchfile and the dummy one as original with MAKECOMPTAB and you will get 
  273. your changestable.
  274.  
  275. Examples:
  276. parambane - Really easy example of alteration of a file (DOS-game)
  277. parampopulous - to show some abilities of the patcher of altering files
  278. paramcarriercommand - (historical) creates an executable with the data
  279.     of a NONDOS-disk (use now whdload/jst instead of a file if you patch!)
  280. encounter.imager - Basic example for imagers. Use this if you create own ones
  281. nitro.imager - Shows the abilities of The Patcher in (nearly) their entire
  282.     range
  283. wotd.imager - example for multidisk-imaging, sectorized disk
  284.